Skip to main content

Using REST API - Acquire Access Token for Authentication

This shall walk you through how you may obtain an authentication token in VIDIZMO using REST APIs. For more details, see: REST API Reference Guide - Authentication.

Acquire Access Token​

User Credentials​

Following is an example of how a bearer token can be obtained as well as the flow diagram:

Request Method: POST

Request URL: /api/v1/user/authenticate

https://{{your-domain}}/api/v1/user/authenticate

Request Body:

{ 
    "emailAddress":"john.doe@gmail.com",
    "password": "examplepassword"
}

Response Status Code:

200

Response Body:

N2UCSNDDGI4NND5NMBZLV7ZBV2I3BZLUWQFXF6MGZKXTOCLHPH2SLPR2TMPM54M7CTG4DLFNE5KHSZ4LARTLQVRRCCRFAGVAG242M5RB3S5D4TEXKTSH4AHNMLTB3IF5IZYI4XSHRDDF2YFPLYAEMQL3Y3BKGZHCSDC2T2DQY64RC5Q3R5CQ

Client Secret​

This method uses the user's email address and a Client Secret that is generated in the Authentication App created in the VIDIZMO portal. To learn more about Client Secret, see Authentications Methods in VIDIZMO

Request Method: POST

Request URL: /api/v1/user/authenticate

https://{{your-domain}}/api/v1/user/authenticate

Request Body:

{ 
    "emailAddress":"john.doe@gmail.com", 
    "clientSecret": "exampleclientsecret"
}

Response Status Code:

200

Response Body:

N2UCSNDDGI4NND5NMBZLV7ZBV2I3BZLUWQFXF6MGZKXTOCLHPH2SLPR2TMPM54M7CTG4DLFNE5KHSZ4LARTLQVRRCCRFAGVAG242M5RB3S5D4TEXKTSH4AHNMLTB3IF5IZYI4XSHRDDF2YFPLYAEMQL3Y3BKGZHCSDC2T2DQY64RC5Q3R5CQ

Once a bearer token is obtained, then they can be passed in the header of the HTTP request to the VIDIZMO API for requesting further information. Further HTTP Requests can be made using the Authentication Token obtained. Here is how the authorization flow takes place. After VIDIZMO application receives the authentication token, it verifies whether the user to whom the token belongs is authorized to perform the action in the request. If the user is allowed to perform the action, then the call is successfully executed, otherwise an exception is thrown for unauthorized access.

When you try sending a HTTP Request with an invalid Access Token in the Request Header, the following is received:

Response Status Code:

400

Response Body:

{ 
    "name": "InvalidAccessTokenException", 
    "incidentId": "167c0274-515e-4f16-a309-449c9573e9c6"
    "exceptionDetails": [] 
}

What happens when token expires​

A bearer token that has been generated can expire in two cases:

  1. When a user is made to log out via {{your-domain}}/api/v1/user/logout API.
  2. When a user is automatically logged out after the said duration of their token expiry (The default time for OAuth token to expire is 1 day).

VIDIZMO APIs will not be able to perform the action that is requested when a token has expired.

Following is an example of a scenario when a bearer token has expired:

Request Method: GET

Request URL:  /api/v1/user/{emailAddress}

https://{{your-domain}}/api/v1/user/esther.fray%40gmail.com?userPartsToFetch=BasicInfo

Request Header:

Authorization: Bearer <you-bearer-token> Content-Type: application/json

Response Status Code:

400

Response Body:  

{ 
    "name": "ExpiredAccessTokenException", 
    "incidentId": "332d7070-78b3-4730-b76f-7a5adafeab31", 
    "exceptionDetails": [] 
}

Refresh Access Token​

Once a token expires, you will have to refresh it in order to obtain a new valid token for authentication. Here is how you can do that:

Request Method:  POST

Request URL: /api/v1/user/refresh-access-token

https://{{your-domain}}/api/v1/user/refresh-access-token/

Response Status Code:

200

Response Body:

<refreshed bearer token>